<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Documentation Authoring</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REV="MADE"
HREF="mailto:pgsql-docs@postgresql.org"><LINK
REL="HOME"
TITLE="PostgreSQL 9.1.2 Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="Documentation"
HREF="docguide.html"><LINK
REL="PREVIOUS"
TITLE="Building The Documentation"
HREF="docguide-build.html"><LINK
REL="NEXT"
TITLE="Style Guide"
HREF="docguide-style.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
HTTP-EQUIV="Content-Type"
CONTENT="text/html; charset=ISO-8859-1"><META
NAME="creation"
CONTENT="2011-12-01T22:07:59"></HEAD
><BODY
CLASS="SECT1"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="5"
ALIGN="center"
VALIGN="bottom"
><A
HREF="index.html"
>PostgreSQL 9.1.2 Documentation</A
></TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
TITLE="Building The Documentation"
HREF="docguide-build.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="docguide.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="60%"
ALIGN="center"
VALIGN="bottom"
>Appendix I. Documentation</TD
><TD
WIDTH="20%"
ALIGN="right"
VALIGN="top"
><A
TITLE="Style Guide"
HREF="docguide-style.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="DOCGUIDE-AUTHORING"
>I.4. Documentation Authoring</A
></H1
><P
>    <ACRONYM
CLASS="ACRONYM"
>SGML</ACRONYM
> and <SPAN
CLASS="PRODUCTNAME"
>DocBook</SPAN
> do
    not suffer from an oversupply of open-source authoring tools. The
    most common tool set is the
    <SPAN
CLASS="PRODUCTNAME"
>Emacs</SPAN
>/<SPAN
CLASS="PRODUCTNAME"
>XEmacs</SPAN
>
    editor with appropriate editing mode.  On some systems
    these tools are provided in a typical full installation.
   </P
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN138508"
>I.4.1. Emacs/PSGML</A
></H2
><P
>     <SPAN
CLASS="PRODUCTNAME"
>PSGML</SPAN
> is the most common and most
     powerful mode for editing <ACRONYM
CLASS="ACRONYM"
>SGML</ACRONYM
> documents.
     When properly configured, it will allow you to use
     <SPAN
CLASS="APPLICATION"
>Emacs</SPAN
> to insert tags and check markup
     consistency.  You could use it for <ACRONYM
CLASS="ACRONYM"
>HTML</ACRONYM
> as
     well.  Check the <A
HREF="http://www.lysator.liu.se/projects/about_psgml.html"
TARGET="_top"
>     PSGML web site</A
> for downloads, installation instructions, and
     detailed documentation.
    </P
><P
>     There is one important thing to note with
     <SPAN
CLASS="PRODUCTNAME"
>PSGML</SPAN
>: its author assumed that your
     main <ACRONYM
CLASS="ACRONYM"
>SGML</ACRONYM
> <ACRONYM
CLASS="ACRONYM"
>DTD</ACRONYM
> directory
     would be <TT
CLASS="FILENAME"
>/usr/local/lib/sgml</TT
>.  If, as in the
     examples in this chapter, you use
     <TT
CLASS="FILENAME"
>/usr/local/share/sgml</TT
>, you have to
     compensate for this, either by setting
     <TT
CLASS="ENVAR"
>SGML_CATALOG_FILES</TT
> environment variable, or you
     can customize your <SPAN
CLASS="PRODUCTNAME"
>PSGML</SPAN
> installation
     (its manual tells you how).
    </P
><P
>     Put the following in your <TT
CLASS="FILENAME"
>~/.emacs</TT
>
     environment file (adjusting the path names to be appropriate for
     your system):

</P><PRE
CLASS="PROGRAMLISTING"
>; ********** for SGML mode (psgml)

(setq sgml-omittag t)
(setq sgml-shorttag t)
(setq sgml-minimize-attributes nil)
(setq sgml-always-quote-attributes t)
(setq sgml-indent-step 1)
(setq sgml-indent-data t)
(setq sgml-parent-document nil)
(setq sgml-exposed-tags nil)
(setq sgml-catalog-files '("/usr/local/share/sgml/catalog"))

(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )</PRE
><P>

     and in the same file add an entry for <ACRONYM
CLASS="ACRONYM"
>SGML</ACRONYM
>
     into the (existing) definition for
     <TT
CLASS="VARNAME"
>auto-mode-alist</TT
>:
</P><PRE
CLASS="PROGRAMLISTING"
>(setq
  auto-mode-alist
  '(("\\.sgml$" . sgml-mode)
   ))</PRE
><P>
    </P
><P
>     You might find that when using <SPAN
CLASS="PRODUCTNAME"
>PSGML</SPAN
>, a
     comfortable way of working with these separate files of book
     parts is to insert a proper <TT
CLASS="LITERAL"
>DOCTYPE</TT
>
     declaration while you're editing them.  If you are working on
     this source, for instance, it is an appendix chapter, so you
     would specify the document as an <SPAN
CLASS="QUOTE"
>"appendix"</SPAN
> instance
     of a DocBook document by making the first line look like this:

</P><PRE
CLASS="PROGRAMLISTING"
>&lt;!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.2//EN"&gt;</PRE
><P>

     This means that anything and everything that reads
     <ACRONYM
CLASS="ACRONYM"
>SGML</ACRONYM
> will get it right, and I can verify the
     document with <TT
CLASS="COMMAND"
>nsgmls -s docguide.sgml</TT
>.  (But
     you need to take out that line before building the entire
     documentation set.)
    </P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN138537"
>I.4.2. Other Emacs Modes</A
></H2
><P
>     <SPAN
CLASS="PRODUCTNAME"
>GNU Emacs</SPAN
> ships with a different
     <ACRONYM
CLASS="ACRONYM"
>SGML</ACRONYM
> mode, which is not quite as powerful as
     <SPAN
CLASS="PRODUCTNAME"
>PSGML</SPAN
>, but it's less confusing and
     lighter weight.  Also, it offers syntax highlighting (font lock),
     which can be very helpful.
     <TT
CLASS="FILENAME"
>src/tools/editors/emacs.samples</TT
> contains
     sample settings for this mode.
    </P
><P
>     Norm Walsh offers a
     <A
HREF="http://nwalsh.com/emacs/docbookide/index.html"
TARGET="_top"
>major mode</A
>
     specifically for DocBook which also has font-lock and a number of features to
     reduce typing.
    </P
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="docguide-build.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="docguide-style.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Building The Documentation</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="docguide.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Style Guide</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>